/*=============================================================================*
 *  Copyright 2004 The Apache Software Foundation
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *=============================================================================*/
package topics;

import topics.expression.TopicExpression;
import java.util.List;

/**
 * Interface for representing a topic. A topic is either a child of a parent topic or in the case of root topics a
 * member of a topic list. Non-root topics have names without a namespace component.
 *
 * @see TopicSpace
 */
public interface Topic
   extends TopicSet,
           TopicListenerList
{
   /**
    * Get the latest notification message published to this topic.
    *
    * @return an Object representing the latest notification message published to this topic, or null if no messages
    *         have yet been published
    */
   Object getCurrentMessage(  );

   /**
    * Get the name of this topic.
    *
    * @return the name of this topic
    */
   String getName(  );

   /**
    * Is this a topic reference?
    *
    * @return true if this topic is a reference to another topic, false if not
    */
   boolean isReference(  );

   /**
    * Set the topic path. The topic path is represented as a ordered list of topic names
    *
    * @param topicPath The topic path to associate with this topic
    */
   void setTopicPath( List topicPath );

   /**
    * Get the topic path. The topic path is represented as a ordered list of topic names
    *
    * @return The topic path of this topic
    */
   List getTopicPath(  );

   /**
    * Set the topic expression that resolves to a set of topics that this topic references.
    * Only used for reference topics.
    *
    * @param topicPath The topic expression to set.
    */
   void setTopicReference( TopicExpression topicPath );

   /**
    * Get the topic expression for the topic(s) that this topic references.
    *
    * @return The topic expression that this topic reference or null if this topic is not a reference.
    */
   TopicExpression getTopicReference(  );

   /**
    * Set the TopicSpace this Topic is part of
    *
    * @param topicSpace The TopicSpace this Topic is part of
    */
   void setTopicSpace( TopicSpace topicSpace );

   /**
    * gets the TopicSpace this Topic is part of
    *
    * @return  The TopicSpace this Topic is part of
    */
   TopicSpace getTopicSpace(  );

   /**
    * Returns whether this Topic is visible or not.
    *
    * @return true if the Topic is visible, else false.
    */
   boolean isVisible(  );

   /**
    * Publish a notification message to this topic.
    *
    * @param msg the notification message to be published
    *
    * @throws Exception on error
    */
   void publish( Object msg )
   throws Exception;
}